PT-4214 Stage U: backend-authoritative per-project S/R block signal (E2E defects 2+3) - #2574

… oldest-first pairing

Review findings 1-3 on #2571: pairing anonymous clears with the oldest
outstanding leash both releases a live blocker (a late clear after a leash
fired cancels a newer switch's leash) and starves an abandoned blocker's own
leash (every clear cancels the leash nearest to firing, so blocking persists
indefinitely under ongoing traffic).

Both stores now hand out one release token per block/switch. A token is
released exactly once - by its own clear or its own leash - and a late clear
after the leash fired is a no-op by identity. The dual counter and the
timer-array scan dissolve (findings 14/15): the live-token set is the single
source of truth.

The project-switch events now carry a switchId (declared in NetworkEvents,
emitted by platform-scripture-editor), so the workspace-updating service
pairs every finish with exactly the switch that started it - both review
traces are fixed end-to-end and pinned by integration tests that fail on the
old code. The auto-sync blocking event remains an anonymous boolean, so that
service keeps oldest-first pairing with tombstones for leash-released raises
(fixes the late-clear trace); the abandoned-raise trace is unfixable on an
anonymous wire and is resolved by the backend-authoritative snapshot model in
#2574, as documented in the service.

Also per findings 5/6/13: the inert getAutoSyncBlocking seeding is cut (the
command is registered nowhere at this tip; the doomed consult cost ~9 s of
main-process retry churn per renderer launch because requestNoRetry's flag
does not cross the wire - now documented on requestNoRetry itself). The
"Known limitation" reload note is restored, pointing at PT-4214, whose C#
SendReceiveBlockNotifierService (#2574) serves the command for real. Cutting
the seed also makes initAutoSyncBlockingService synchronous again, so the
index.tsx startup comment is accurate at this tip.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… oldest-first pairing

Review findings 1-3 on #2571: pairing anonymous clears with the oldest
outstanding leash both releases a live blocker (a late clear after a leash
fired cancels a newer switch's leash) and starves an abandoned blocker's own
leash (every clear cancels the leash nearest to firing, so blocking persists
indefinitely under ongoing traffic).

Both stores now hand out one release token per block/switch. A token is
released exactly once - by its own clear or its own leash - and a late clear
after the leash fired is a no-op by identity. The dual counter and the
timer-array scan dissolve (findings 14/15): the live-token set is the single
source of truth.

The project-switch events now carry a switchId (declared in NetworkEvents,
emitted by platform-scripture-editor), so the workspace-updating service
pairs every finish with exactly the switch that started it - both review
traces are fixed end-to-end and pinned by integration tests that fail on the
old code. The auto-sync blocking event remains an anonymous boolean, so that
service keeps oldest-first pairing with tombstones for leash-released raises
(fixes the late-clear trace); the abandoned-raise trace is unfixable on an
anonymous wire and is resolved by the backend-authoritative snapshot model in
#2574, as documented in the service.

Also per findings 5/6/13: the inert getAutoSyncBlocking seeding is cut (the
command is registered nowhere at this tip; the doomed consult cost ~9 s of
main-process retry churn per renderer launch because requestNoRetry's flag
does not cross the wire - now documented on requestNoRetry itself). The
"Known limitation" reload note is restored, pointing at PT-4214, whose C#
SendReceiveBlockNotifierService (#2574) serves the command for real. Cutting
the seed also makes initAutoSyncBlockingService synchronous again, so the
index.tsx startup comment is accurate at this tip.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

… oldest-first pairing

Review findings 1-3 on #2571: pairing anonymous clears with the oldest
outstanding leash both releases a live blocker (a late clear after a leash
fired cancels a newer switch's leash) and starves an abandoned blocker's own
leash (every clear cancels the leash nearest to firing, so blocking persists
indefinitely under ongoing traffic).

Both stores now hand out one release token per block/switch. A token is
released exactly once - by its own clear or its own leash - and a late clear
after the leash fired is a no-op by identity. The dual counter and the
timer-array scan dissolve (findings 14/15): the live-token set is the single
source of truth.

The project-switch events now carry a switchId (declared in NetworkEvents,
emitted by platform-scripture-editor), so the workspace-updating service
pairs every finish with exactly the switch that started it - both review
traces are fixed end-to-end and pinned by integration tests that fail on the
old code. The auto-sync blocking event remains an anonymous boolean, so that
service keeps oldest-first pairing with tombstones for leash-released raises
(fixes the late-clear trace); the abandoned-raise trace is unfixable on an
anonymous wire and is resolved by the backend-authoritative snapshot model in
#2574, as documented in the service.

Also per findings 5/6/13: the inert getAutoSyncBlocking seeding is cut (the
command is registered nowhere at this tip; the doomed consult cost ~9 s of
main-process retry churn per renderer launch because requestNoRetry's flag
does not cross the wire - now documented on requestNoRetry itself). The
"Known limitation" reload note is restored, pointing at PT-4214, whose C#
SendReceiveBlockNotifierService (#2574) serves the command for real. Cutting
the seed also makes initAutoSyncBlockingService synchronous again, so the
index.tsx startup comment is accurate at this tip.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

- Canonicalize project ids to upper at ingestion + in both readers (isEditorBlocked, isProjectBlocked) so a casing skew can't leave a project silently unblocked
- applyBlockedSetToAllEditors reports success; syncState only advances the applied snapshot on a successful apply (open-but-unenumerable editors no longer recorded as flagged)
- Subscribe to the gate before the event-registration round-trip so no transition is dropped
- Move SendReceiveBlockState to its own file (PNX004); add a shared static NotBlocking snapshot; drop the redundant ToArray copy in GetBlockState
- Reuse deepEqual/isString from platform-bible-utils; scope the dead rawBlockedProjectIds writes to the arming branch
- Add a pointer comment noting the init consult is the only backend re-seed (lost-disarm recovery tracked on PT-4214)
- Fix the now-stale workspace-updating-store cross-reference comment

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…Project @experimental

Per lyonsil's #2574 follow-up: the two new switch-pairing network events (added in #2571) are recently-added PAPI surface whose contract isn't settled. Add per-member @experimental TSDoc (extension .d.ts isn't run through TypeDoc, so each member needs its own tag). Matches the posture of AUTO_SYNC_MAX_DURATION_MS, which #2571 marked.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…ia async emitter with x-experimental

Part 2 of lyonsil's #2574 @experimental follow-up: switch the onWillSwitchProject / onDidSwitchProject emitters from the deprecated sync createNetworkEventEmitter to createNetworkEventEmitterAsync, passing notification docs with 'x-experimental': true so the events are marked experimental in the generated OpenRPC document (not just the .d.ts TSDoc). The enclosing open() handler is already async, so awaiting emitter creation only adds first-use latency and the will-start event still fires before the switch.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…(lyonsil #2574 review)

Sweep the PR's comments per lyonsil's change request: drop change-history / 'PT-4214 Stage U' / 'review finding' / E2E-date justifications and restate each as present-tense documentation of what the code does. Keep genuine forward pointers to open follow-ups (editor-mount re-query, gate arming). papi.d.ts regenerated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…king, onSyncWriteLockChanged) + public breakSyncLock stub (#2612)

* PT-4214: declare the S/R write-gate seam API held out of #2574

Declares in the paratext-bible-send-receive type seam what core PR
#2574 shipped undeclared (held back to avoid colliding with #2570's
seam re-home, which has now merged):

- SyncWriteLockSnapshot payload type (the C# SendReceiveBlockState
  wire shape)
- paratextBibleSendReceive.getAutoSyncBlocking command
- paratextBibleSendReceive.onSyncWriteLockChanged network event

All three are tagged @experimental. The renderer auto-sync-blocking
service now consumes the seam instead of its interim local types:
imports nothing locally-duplicated, subscribes through the typed
getNetworkEvent overload, and sends the init consult through the typed
sendCommand instead of an untyped requestNoRetry (identical wire
behavior from the renderer, where the no-retry flag never crossed the
wire anyway). The fail-safe payload validation stays, since older or
off-contract cores remain possible.

The legacy onAutoSyncBlockingChanged event was never declared in core,
so there is nothing to remove; the test asserting non-subscription is
kept. Regenerating papi.d.ts produces no changes - the src/@types seam
is not part of papi.d.ts generation.

Claude-Session: https://claude.ai/code/session_019MhYcp1XVTQ7JHiA4n2qaV
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* PT-4210 Task 3: public breakSyncLock stub + seam declaration

paratextBibleSendReceive.breakSyncLock so far existed only in the
private Paratext 10 Studio patch, deviating from the public/private
seam convention where core ships the public scaffolding (stub +
declared contract) and the patch only fills in the implementation.

- ParatextProjectSendReceiveService: register the command and add a
  BreakSyncLock stub throwing PlatformUnimplementedException, following
  the cancelSync/syncProjects pattern and phrasing. The signature
  matches the patch's implementation (List<string> projectIds ->
  Task<Dictionary<string, bool>>) so the patch converts to a body fill;
  the stub is non-async to avoid CS1998, so the patch also adds the
  async keyword. The patch-only s_sendReceiveTimeout registration
  argument stays in the patch, like syncProjects.
- Seam d.ts: declare the command in CommandHandlers, copied from the
  Send/Receive extension's own declaration, plus the seam's standard
  PlatformUnimplementedException @throws note. Tagged @experimental.

No core registration-list test or doc enumerates these commands, so
nothing else to extend.

Claude-Session: https://claude.ai/code/session_019MhYcp1XVTQ7JHiA4n2qaV
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* PT-4210: address review round — wire experimental docs, PT-4265 pointer, breakSyncLock doc clarifications

- breakSyncLock and getAutoSyncBlocking registrations now pass
  ExperimentalMethodDocumentation so the x-experimental marker reaches the
  wire (OpenRPC rpc.discover), per the Experimental APIs standard.
- Update the editor-mount re-query tracking pointer from the closed PT-4214
  to its surviving ticket PT-4265.
- breakSyncLock docs (TS + C# XML) now state it breaks the SERVER-side
  repository lock and is unrelated to the local in-process write gate
  reported by onSyncWriteLockChanged / getAutoSyncBlocking.
- Document breakSyncLock's empty-array behavior (verified against the real
  implementation): empty input is a no-op — empty result map, server never
  contacted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019MhYcp1XVTQ7JHiA4n2qaV

* PT-4210: give ParatextProjectSendReceiveService a LocalParatextProjects reference

Adds a LocalParatextProjects constructor parameter (bound into a property by the
closed-source Paratext 10 Studio overlay patch, like pdpFactory and appInfo) so the
patch can call NotifyProjectsChanged after a sync rewrites Settings.xml in place —
the file watcher's own docs say such in-place rewrites must be notified inline by
their writer. Part of the PT-4158 deferred-items cleanup.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019MhYcp1XVTQ7JHiA4n2qaV

* PT-4210: public-core D1 additions — S/R timeout on breakSyncLock, RefreshAndNotifyProjectsChanged, init snapshot emit

- breakSyncLock's stub registration now passes the indefinite S/R timeout
  itself (internal s_sendReceiveTimeout, matching the P10S overlay's name
  so the two unify): S/R commands are multi-minute server operations, so
  the request timeout must outlive them. Inert in plain Platform.Bible
  since the stub throws immediately.
- New public virtual LocalParatextProjects.RefreshAndNotifyProjectsChanged():
  RefreshScrTexts + NotifyProjectsChanged as one primitive for writers whose
  on-disk changes are invisible to the non-recursive project-directory
  watcher (in-place Settings.xml rewrites, mid-clone states).
- Moved the notify-after-sync integration rationale from the SyncProjects
  stub body (which the overlay replaces wholesale) to the constructor
  comment, and pointed it at the new primitive.
- SendReceiveBlockNotifierService.InitializeAsync now emits the current
  gate snapshot once after registration, so subscribers converge after a
  backend restart; tests cover the idle and already-armed cases.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pBpGFRLUt3fioxfz45jnU

* PT-4210: review-round code fixes — event wire docs, parallel registrations, stub fault mode, renderer hardening

- New OpenRpcSingleNotificationDocumentation/OpenRpcNotificationDocumentation
  records (C# mirror of TS SingleNotificationDocumentation) and the
  onSyncWriteLockChanged registration now sends them as network:registerEvent's
  second argument, carrying the x-experimental wire marker (review 1).
- SendReceiveBlockNotifierService registers its event and command in parallel
  via Task.WhenAll, so a stalled main can't serialize two full request
  timeouts onto the startup barrier (17).
- BreakSyncLock stub delivers its PlatformUnimplementedException through the
  returned task, matching the patched async implementation's fault mode (25).
- SyncProjects' dev placeholder uses the PapiClient property instead of the
  raw ctor param, clearing the CS9124 double-capture warning (27).
- Renderer auto-sync-blocking-service: malformed-snapshot warnings now name
  their source (event vs init query) and latch per source (4); projectIds
  validation uses .every(isString) (24); the init-consult failure docs
  describe the real cold-start race instead of unreachable "older cores /
  extension absent" scenarios, and the catch logs warn instead of debug
  since any rejection is anomalous on an in-repo seam (3); same reword on
  the seam's getAutoSyncBlocking declaration.
- Doc-assertion tests per the VersificationConversionServiceTests precedent:
  getAutoSyncBlocking + the event registration docs in the notifier tests,
  and a new ParatextProjectSendReceiveServiceStubDocsTests for breakSyncLock
  (named to avoid the P10S overlay's test file names) (5).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pBpGFRLUt3fioxfz45jnU

* PT-4210: review-round docs/comments — breakSyncLock contract detail, seam re-sync guard, mock typing

- breakSyncLock wire summary gains the build-agnostic availability sentence
  ("Only implemented in Paratext 10 Studio; throws
  PlatformUnimplementedException elsewhere") and the registration uses the
  named documentation: argument (2, 29); dropped the comment that only
  restated the x-experimental marker (23).
- Seam d.ts: `false` means "not broken — an attempt may not have been made;
  a later retry can succeed" (6a); keys are upper-cased, index with
  upper-cased ids (7); null/blank ids are skipped and omitted (8); the
  header NOTE now also forbids a re-sync downgrading richer declarations
  that exist in both copies (10).
- auto-sync-blocking-service: seed + event handler carry
  "typed-by-the-seam but untrusted wire data" pinning comments (16); the
  free-floating payload-type comment is now a one-line pointer to the seam
  declaration (21); noted that plain sendCommand (retry-on-timeout) is
  deliberate now that the command is declared — requestNoRetry was only a
  workaround for the missing declaration (S1).
- Tests: the two well-formed snapshot mocks are pinned with
  `satisfies SyncWriteLockSnapshot`; deliberately-malformed ones stay
  untyped (15).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pBpGFRLUt3fioxfz45jnU

* PT-4210: bind the patch-bound ctor params into core-side properties (D2b)

Replace the CS9113 pragma (and its unread-parameter rationale comment) with
read-only auto-properties PdpFactory / AppInfo / ParatextProjects in the
PapiClient property's style, using exactly the names the Paratext 10 Studio
patch's own bindings use so the patch can drop its binding hunk and rely on
these. The params are now consumed by the initializers, so no suppression
is needed; a guard comment marks the properties as patch-only reads that
must not be removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015pBpGFRLUt3fioxfz45jnU

* PT-4210: review-round fixes — refresh/notify funnel, syncProjects timeout, awaited baseline emit, doc truth-up

Four approved fixes from timothy-mccormack's 2026-07-29 review round:

1. LocalParatextProjects: RefreshAndNotifyProjectsChanged now carries the
   best-effort contract itself (refresh in try, notify after catch — a
   refresh throw must not suppress the notify) plus the class-convention
   _disposed early-return guard, and OnProjectDirectoriesChanged delegates
   to it so the inline and watcher paths share one funnel. New test pins
   the delegation.

2. ParatextProjectSendReceiveService: the syncProjects registration now
   carries s_sendReceiveTimeout like breakSyncLock, and the field's
   comment covers both rationales (multi-minute whole-project syncs; the
   lock-break's potentially N x ~100s server calls) and states that 0 is
   deliberately unbounded — only a lost response on a live socket waits
   forever, a risk every S/R command shares.

3. SendReceiveBlockNotifierService: the init baseline snapshot emit is
   now AWAITED (best-effort, logged on failure) so the startup barrier
   (Program.cs's critical Task.WhenAll) guarantees the baseline emit
   precedes any command-driven gate arm's event; InitializeAsync doc
   notes the ordering guarantee.

4. Docs, three sites (TS seam NetworkEvents entry, the C# class doc,
   auto-sync-blocking-service.ts): "plain Platform.Bible never emits it"
   was falsified by the baseline emit — now phrased as "the gate never
   arms in plain PB; the only plain-PB emission is a single not-blocking
   baseline snapshot at backend (re)start". BlockStateChanged never
   firing in plain PB remains stated.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187X1kRaKEf634749ZDqh5A

* doc: PT-4210 note breakSyncLock id trimming + case-variant collapse in @PARAM docs

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187X1kRaKEf634749ZDqh5A

* doc: PT-4210 correct InitializeAsync baseline-emit ordering claim

Task.WhenAll does not order its members, and the S/R command registrations
share the startup barrier with this service, so a mid-barrier command can
arm the gate and emit before the baseline — the previous doc claimed the
barrier made that impossible. State what actually holds: the emit attempt
completes before the barrier returns; post-barrier arms emit strictly
behind it (single connection, FIFO); a mid-barrier arm that beats the
baseline is reflected in it (GetBlockState() is a live read at emit time)
rather than overwritten by a stale not-blocking snapshot; late subscribers
seed via getAutoSyncBlocking.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187X1kRaKEf634749ZDqh5A

* fix: PT-4210 make debounce-timer disposal atomic with scheduling

NotifyProjectsChanged and ScheduleProjectDirectoriesChanged checked
_disposed before taking their debounce lock, while Dispose tore the
timers down outside those locks - so a call racing Dispose could Change
an already-disposed timer (ObjectDisposedException) or, worse, construct
a brand-new timer after Dispose that nothing ever disposes and that
later emits against a disposing PapiClient.

Move each _disposed check inside its debounce lock and dispose each
timer under that same lock, making check-then-schedule atomic with the
teardown (deadlock-free: no timer callback holds these locks while
waiting on Dispose, and Timer.Dispose() does not block on in-flight
callbacks). Also give EmitProjectsChanged a _disposed back-off as a
second line of defence for a callback already in flight at disposal.

The race window (between check and lock) is not reachable
deterministically from the existing test seams, so the invariant is
documented on Dispose instead of pinned by a test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187X1kRaKEf634749ZDqh5A

* doc: PT-4210 note breakSyncLock null-array behavior in @PARAM docs

A null projectIds array is out of contract (the type is string[]);
implementations treat it like the empty array (no-op).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0187X1kRaKEf634749ZDqh5A

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>